#方圆.py (稳定版，无动画)
"""
一个使用更自然语言和增强视觉效果的 PySide6 辅助函数库。
目标是让创建 GUI 更像在写说明书。
注意：必须在主程序中先创建 QApplication 实例。
或者使用库中提供的 '启动应用程序' 函数。
"""

import sys
# --- 正确的导入方式 ---
# 从 QtWidgets 导入所有需要的控件和效果 (包括 QGraphicsDropShadowEffect)
# 同时导入 QMessageBox 的角色常量等
from PySide6.QtWidgets import (
    QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QGridLayout,
    QLabel, QPushButton, QLineEdit, QTextEdit, QListWidget, QListWidgetItem,
    QMessageBox,
    QFrame, QGraphicsDropShadowEffect,
    QApplication, QSpacerItem, QSizePolicy
)
# 从 QtGui 导入图形相关
from PySide6.QtGui import (
    QFont, QColor, QPalette, QIcon, QPixmap,
    QPainter, QLinearGradient, QBrush,
    QTextCursor
)
# 从 QtCore 导入核心功能和常用类
from PySide6.QtCore import (
    Qt, QTimer, QRect, QPoint,
    QSize, QUrl, QDate, QTime, QDateTime
)
# --- 正确的导入方式 结束 ---


# --- 核心窗口和布局 ---

def 创建主窗口(标题="我的应用", 宽度=600, 高度=400):
    """
    创建并配置一个 QMainWindow 实例。
    注意：调用此函数前，必须已经通过 QApplication(sys.argv) 创建了 QApplication 实例。
    """
    窗口 = QMainWindow()
    窗口.setWindowTitle(标题)
    窗口.resize(宽度, 高度)
    return 窗口


def 为窗口设置中央区域和布局(窗口, 布局类型="垂直", 内边距=20, 间距=15):
    """
    为 QMainWindow 设置中央部件和布局管理器
    布局类型: "垂直", "水平", "网格"
    """
    中央区域 = QWidget()
    窗口.setCentralWidget(中央区域)

    if 布局类型 == "垂直":
        布局管理器 = QVBoxLayout()
    elif 布局类型 == "水平":
        布局管理器 = QHBoxLayout()
    elif 布局类型 == "网格":
        布局管理器 = QGridLayout()
    else:
        布局管理器 = QVBoxLayout()  # 默认垂直

    布局管理器.setContentsMargins(内边距, 内边距, 内边距, 内边距)
    布局管理器.setSpacing(间距)
    中央区域.setLayout(布局管理器)
    return 中央区域, 布局管理器

def 为控件设置布局(控件, 布局类型="垂直", 内边距=20, 间距=15):
    """
    为普通的 QWidget 设置布局管理器。
    与 '为窗口设置中央区域和布局' 不同，此函数直接在控件上设置布局。
    用于自定义页面或控件。
    布局类型: "垂直", "水平", "网格"
    """
    if 布局类型 == "垂直":
        布局管理器 = QVBoxLayout()
    elif 布局类型 == "水平":
        布局管理器 = QHBoxLayout()
    elif 布局类型 == "网格":
        布局管理器 = QGridLayout()
    else:
        布局管理器 = QVBoxLayout()  # 默认垂直

    布局管理器.setContentsMargins(内边距, 内边距, 内边距, 内边距)
    布局管理器.setSpacing(间距)
    控件.setLayout(布局管理器)
    return 控件, 布局管理器


# --- 美化和样式 ---

def 应用全局样式(窗口, 背景颜色="#F0F0F0", 字体="微软雅黑", 字号=12):
    """
    应用全局样式到窗口
    """
    样式表 = f"""
        QMainWindow {{
            background-color: {背景颜色};
            font-family: "{字体}";
            font-size: {字号}px;
        }}
        QWidget {{
            color: #333333;
        }}
    """
    窗口.setStyleSheet(样式表)


def 使控件具有样式(控件, 样式规则):
    """
    为单个控件应用内联样式
    样式规则是一个字典，例如：
    {{
        "背景颜色": "#FF5722",
        "文字颜色": "#FFFFFF",
        "边框": "1px solid #333333",
        "圆角": "10px",
        "字体大小": "16px",
        "内边距": "10px"
    }}
    """
    样式字符串 = ""
    if "背景颜色" in 样式规则:
        样式字符串 += f"background-color: {样式规则['背景颜色']};"
    if "文字颜色" in 样式规则:
        样式字符串 += f"color: {样式规则['文字颜色']};"
    if "字体大小" in 样式规则:
        样式字符串 += f"font-size: {样式规则['字体大小']};"
    if "字体" in 样式规则:
        样式字符串 += f"font-family: {样式规则['字体']};"
    if "字体粗细" in 样式规则:
        样式字符串 += f"font-weight: {样式规则['字体粗细']};"
    if "字体样式" in 样式规则:
        样式字符串 += f"font-style: {样式规则['字体样式']};"
    if "行高" in 样式规则:
        样式字符串 += f"line-height: {样式规则['行高']};"
    if "边框" in 样式规则:
        样式字符串 += f"border: {样式规则['边框']};"
    if "圆角" in 样式规则:
        样式字符串 += f"border-radius: {样式规则['圆角']};"
    if "内边距" in 样式规则:
        样式字符串 += f"padding: {样式规则['内边距']};"
    if "外边距" in 样式规则:
        样式字符串 += f"margin: {样式规则['外边距']};"
    if "最小宽度" in 样式规则:
        样式字符串 += f"min-width: {样式规则['最小宽度']};"
    if "最小高度" in 样式规则:
        样式字符串 += f"min-height: {样式规则['最小高度']};"
    if "最大宽度" in 样式规则:
        样式字符串 += f"max-width: {样式规则['最大宽度']};"
    if "最大高度" in 样式规则:
        样式字符串 += f"max-height: {样式规则['最大高度']};"
    控件.setStyleSheet(样式字符串)


# --- 控件创建 ---

def 添加标签到布局(布局, 文字="", 对齐方式="居中"):
    """添加一个标签到布局"""
    标签 = QLabel(文字)
    if 对齐方式 == "居中":
        标签.setAlignment(Qt.AlignCenter)
    elif 对齐方式 == "左对齐":
        标签.setAlignment(Qt.AlignLeft | Qt.AlignVCenter)
    elif 对齐方式 == "右对齐":
        标签.setAlignment(Qt.AlignRight | Qt.AlignVCenter)
    布局.addWidget(标签)
    return 标签


def 添加按钮到布局(布局, 文字="点击我", 点击时执行=None, 样式=None):
    """添加一个按钮到布局"""
    按钮 = QPushButton(文字)
    if 点击时执行:
        按钮.clicked.connect(点击时执行)
    if 样式:
        使控件具有样式(按钮, 样式)
    布局.addWidget(按钮)
    return 按钮


def 添加输入框到布局(布局, 提示文字="", 样式=None):
    """添加一个单行输入框到布局"""
    输入框 = QLineEdit()
    if 提示文字:
        输入框.setPlaceholderText(提示文字)
    if 样式:
        使控件具有样式(输入框, 样式)
    布局.addWidget(输入框)
    return 输入框


def 添加文本框到布局(布局, 提示文字="", 只读=False, 样式=None):
    """添加一个多行文本框到布局"""
    文本框 = QTextEdit()
    if 提示文字:
        文本框.setPlaceholderText(提示文字)
    if 只读:
        文本框.setReadOnly(True)
    if 样式:
        使控件具有样式(文本框, 样式)
    布局.addWidget(文本框)
    return 文本框


def 添加列表框到布局(布局, 样式=None):
    """添加一个列表框到布局"""
    列表框 = QListWidget()
    if 样式:
        使控件具有样式(列表框, 样式)
    布局.addWidget(列表框)
    return 列表框


# --- 布局管理 ---

def 在布局中添加弹性空间(布局, 方向="垂直"):
    """在布局中添加弹性空间"""
    if 方向 == "垂直":
        布局.addStretch()
    # 可以根据需要扩展支持水平弹性空间等


def 在布局中添加间距(布局, 大小=10):
    """在布局中添加固定间距"""
    布局.addSpacing(大小)


# --- 对话框 ---

def 显示信息(父窗口, 标题, 内容):
    """显示信息对话框"""
    QMessageBox.information(父窗口, 标题, 内容)


def 显示警告(父窗口, 标题, 内容):
    """显示警告对话框"""
    QMessageBox.warning(父窗口, 标题, 内容)


def 显示错误(父窗口, 标题, 内容):
    """显示错误对话框"""
    QMessageBox.critical(父窗口, 标题, 内容)


def 询问是或否(父窗口, 标题, 问题):
    """显示是/否确认对话框"""
    回复 = QMessageBox.question(父窗口, 标题, 问题, QMessageBox.Yes | QMessageBox.No)
    return 回复 == QMessageBox.Yes


# --- 高级控件和效果 ---

def 添加带阴影的框架到布局(布局, 背景颜色="#FFFFFF", 圆角=10, 阴影模糊=15, 阴影偏移Y=5):
    """
    添加一个带阴影效果的框架 (模拟 macOS 卡片效果)
    """
    框架 = QFrame()
    框架.setStyleSheet(f"""
        QFrame {{
            background-color: {背景颜色};
            border-radius: {圆角}px;
        }}
    """)

    阴影 = QGraphicsDropShadowEffect()
    阴影.setBlurRadius(阴影模糊)
    阴影.setXOffset(0)
    阴影.setYOffset(阴影偏移Y)
    阴影.setColor(QColor(0, 0, 0, 50))
    框架.setGraphicsEffect(阴影)

    框架布局 = QVBoxLayout(框架)
    框架布局.setContentsMargins(20, 20, 20, 20)

    布局.addWidget(框架)
    return 框架, 框架布局


# --- 列表操作 ---

def 向列表添加可勾选项目(列表框, 文字, 已完成=False):
    """向列表添加一个可勾选的项目"""
    项目 = QListWidgetItem(文字)
    if 已完成:
        项目.setCheckState(Qt.Checked)
    else:
        项目.setCheckState(Qt.Unchecked)
    列表框.addItem(项目)
    return 项目


def 切换列表项目状态(项目):
    """切换列表项目的勾选状态"""
    if 项目.checkState() == Qt.Checked:
        项目.setCheckState(Qt.Unchecked)
    else:
        项目.setCheckState(Qt.Checked)


# --- 实用工具函数 ---

def 简单居中窗口(窗口):
    """
    一个简单的窗口居中函数，在窗口显示后调用。
    """
    桌面 = QApplication.primaryScreen().availableGeometry()
    窗口大小 = 窗口.frameGeometry()
    中心点 = 桌面.center()
    窗口.move(中心点 - QPoint(窗口大小.width() // 2, 窗口大小.height() // 2))


# --- 应用程序启动 ---

def 启动应用程序_说明性(创建界面函数):
    """
    [不推荐] 启动 Qt 应用程序的辅助函数。
    """
    import sys
    应用实例 = QApplication.instance()
    if 应用实例 is None:
        应用 = QApplication(sys.argv)
    else:
        应用 = 应用实例

    窗口 = 创建界面函数()
    窗口.show()
    sys.exit(应用.exec())

# --- 中文函数库.py 结束 ---
